Skip to main content

HTMLText

Type​

property

Summary​

Specifies the contents of a field, including all text styles and paragraph formatting, represented as HTML tags and special characters represented as HTML entities.

Syntax​

set the HTMLText of [<chunk> of] <field> to <htmlString>
get the [effective] HTMLText of [<chunk> of] <field>

Description​

Use the HTMLText property to copy or export a field's contents with the text and paragraph formatting intact. Setting the HTMLText of a field can also be a way of displaying simple HTML-formatted text from a web page or external file. It should be emphasized that the HTMLText property is not a complete HTML rendering engine. Instead, it can be understood as a way to faithfully represent the entire contents of a field, including text and paragraph formatting, using HTML-style tags and attributes.

The HTMLText of a field or chunk is a string. If the effective keyword is specified the HTMLText property returns the HTML of the field with explicit formatting. For example if the textFont of the stack is set this is not included in the HTMLText but is included in the effective HTMLText.

The HTMLText property is a representation of the styled text and paragraph formatting of the field. LiveCode uses a subset of HTML tags that includes font, size, style, and text color information, along with paragraph alignment, indentation, spacing, padding and other information.

Setting the HTMLText of a field (or a chunk of a field) sets both the text contents and the style attributes corresponding to the tags listed below. (Other tags are ignored.)

Getting the HTMLText property reports a string consisting of the text of the field (or chunk of a field), with any font, size, style, or color properties embedded in the text in the form of the tags listed below.

The tags translate as follows:

<p> </p> Encloses a line of text. (Blank lines are also enclosed in <p> </p>.) These properties are represented as attributes of the <p> tag:

  • align="left|center|right" appears if an alignment has been applied to the line.
  • firstindent="N" (where N is an integer representing number of pixels) appears if the firstIndent has been set for the line.
  • leftindent="N" appears if the leftIndent has been set for the line.
  • rightindent="N" appears if the rightIndent has been set for the line.
  • spaceabove="N" appears if the spaceAbove has been set for the line.
  • spacebelow="N" appears if the spaceBelow has been set for the line.
  • tabstops="N" appears if tabStops have been set for the line.
  • tabAlign="left|center|right[,left|center|right...]" appears if tabAlign has been set for the line.
  • borderwidth="N" if a borderWidth has been set for the line.
  • hgrid="true|false" if the vGrid property has been set for the line.
  • vgrid="true|false" if the hGrid property has been set for the line.
  • dontwrap="true|false" if the dontWrap property has been set for the line.
  • padding="N" if the padding has been set for the line.
  • hidden="true|false" if the hidden property has been set for the line.
  • bgcolor="#NNNNNN" if a backgroundColor has been set for the line.
  • bordercolor="#NNNNNN" if a borderColor has been set for the line.
note

An HTML-style color definition can take one of the two forms. The first consists of a hash mark (#) followed by three 2-digit hexadecimal numbers, one each for red, green, and blue. E.g., "#FF9900" represents an orange color. The second form consists of three comma delimited integers between 0 and 255. E.g. "255,153,0" represents an orange color.

<sub> </sub> Encloses text whose textShift is a positive integer. (The <sub> tag is not nested for additional levels of subscription:it appears once for a run of subscripted text, regardless of the value of the textShift.)

  • shift="N" where N is the number of pixels text is subscripted.

<sup> </sup> Encloses text whose textShift is a negative integer. (The <sup> tag is not nested for additional levels of superscription: it appears once for a run of superscripted text, regardless of the value of the textShift.)

  • shift="-N" where N is the number of pixels text is superscripted.

<i> </i> Encloses text whose textStyle is "italic".

note

If a field is set to HTML text that includes text enclosed by <em> </em>, the tag will be converted to <i> </i>.

<b> </b> Encloses text whose textStyle is "bold".

note

If a field is set to HTML text that includes text enclosed by <strong> </strong>, the tag will be converted to <b> </b>.

<strike> </strike> Encloses text whose textStyle is "strikeout".

<u> </u> Encloses text whose textStyle is "underline".

<box> </box> Encloses text whose textStyle is "box".

<threedbox> </threedbox> Encloses text whose textStyle is "threeDBox".

<font> </font> Encloses text whose textFont, textSize, foregroundColor, or backgroundColor is different from the field's default. These five properties are represented as attributes of the <font> tag.

  • face="fontName" appears in the <font> tag if the textFont is not the default.
  • size="N" (where N is the point size of the font) appears if the textSize is not the default.
  • lang="languageName" appears if the textFont includes a language specification.
  • color="#NNNNNN" appears if the foregroundColor is not the default.
  • bgcolor="#NNNNNN" appears if the backgroundColor is not the default.
note

An HTML-style color definition consists of a hash mark (#) followed by three 2-digit hexadecimal numbers, one each for red, green, and blue. E.g., "#FF9900" represents an orange color.

<ol type="lower latin|upper latin|lower roman|upper roman"> </ol> Encloses lines of text whose listStyle property is one of the following:

  • lower latin
  • upper latin
  • lower roman
  • upper roman

<ul type="disc|circle|square|skip"> </ul> Encloses lines of text whose listStyle property is one of the following:

  • "disc"
  • "circle"
  • "square"
  • "skip"

<li> </li> Encloses a line of text whose listStyle property has been set to one of the listStyles listed above.

<a> </a> Encloses text whose textStyle is "link" or whose linkText property is not empty. If the textStyle of the text contains "link", the linkText is included as the value of the "href" attribute. Otherwise, it is included as the value of the "name" attribute.

<img src="imageSpecifier"> Replaces a character whose imageSource property is not empty. The value of the imageSource property is included as the value of the "src" attribute.

<span metadata="string"> </span> Encloses a run of text whose metadata property is set to the string indicated.

When you set the HTMLText of a field, all tags other than those above are ignored, except heading tags (<h1>--<h6>), which change the size of the text in the heading element:

tagtextSize
<h1>34 point
<h2>24 point
<h3>18 point
<h4>14 point
<h5>12 point
<h6>10 point

When setting the HTMLText of a < field(object) to an HTML-formatted string, you can use LiveCode color references for the "color" and "bgcolor" attributes. LiveCode translates these into standard HTML-style color specifications.

If a chunk of text includes more than one of the above styles, LiveCode encloses the text in the tags corresponding to each style, from the inside out. For example, if the word "Flail" in a field is underlined and bold, its corresponding HTMLText is "<u><b>Flail</b></u>".

Special characters (whose ASCII value is greater than 127) are encoded as HTML entities. Named HTML entities are enclosed by a leading ampersand and trailing semicolon; e.g. &agrave; for à and &euro; for €. LiveCode recognizes all 253 entities defined in the XHTML specification at http://www.w3.org/TR/html4/sgml/entities.html.

Unicode characters whose decimal numeric value is greater than 255 are encoded as "bignum" entities, with a leading ampersand and trailing semicolon. For example, the Japanese character whose numeric value is 12387 is encoded as an entity like this:&#12387;.

note

The HTMLText of a field or chunk includes formatting information for the text, but does not include information about the text properties of the field itself. If you use the HTMLText property to transfer text between fields, you must make sure that the destination field's textFont and other text properties match the settings of the source field, if you want the text in both fields to look identical.

Important

The HTMLText property uses a tag structure that is HTML-like, but is not completely standard HTML, in order to accommodate the full range of text styling available in LiveCode. Specifically:

  • The link, box and threedbox tags, as well as the bgColor attribute of the font tag, have been added to accommodate styles that don't exist in standard HTML.
  • The size attribute of the font tag can encode the font's point size, in addition to the standard 7 HTML sizes.
  • The HTMLText reports entities whose ASCII value is between 129 and 159. These correspond to characters in the Windows character set (Code Page 1252) that are not legal HTML entities.

Examples​

set the HTMLText of field "White Paper" to "&lt;b&gt;&lt;i&gt;Click here!&lt;/i&gt;&lt;/b&gt;"
set the HTMLText of field "Dest" to the HTMLText of field "Source"
write the HTMLText of field "Story" to file myWebFile
put the effective htmlText of field "description"
set the HTMLText of field "display" to URL "http://www.server.com/somepage.html"

property: backgroundColor, borderColor, borderWidth, dontWrap, dragData, firstIndent, foregroundColor, hGrid, hidden, HTMLText, imageSource, leftIndent, linkText, listStyle, metadata, mimeText, padding, rightIndent, RTFText, spaceAbove, spaceBelow, tabAlign, tabStops, textAlign, textFont, textShift, textSize, textStyle, unicodeText, vGrid

command: get, set

function: charToNum, colorNames, format, numToChar, fontLanguage

glossary: character set, chunk, default, encode, format, hexadecimal, HTML, integer, negative, property, string, Windows

keyword: effective, field, URL

object: field

Compatibility and Support​

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile

Thank you for your feedback!

Was this page helpful?

Tags: